home *** CD-ROM | disk | FTP | other *** search
/ MacHome 2001 May / MacHome CD (May 2001).iso / mac / Stuff / Software / Tools / The Fragmalyzer 1.5.1 / Extras / Headers & Libraries / FrazAPI.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-11-08  |  12.3 KB  |  476 lines  |  [TEXT/CWIE]
  1. /*     
  2.     File:      FrazAPI.h
  3.     
  4.     Fragmalyzer Plug-in Interface
  5.     
  6.     Version:    1.5
  7.     Date:     August 2000
  8.     
  9.     Copyright © 1998-2000 Dan Wright, All rights reserved.
  10.     
  11.     Bugs?:     Please include the name of this file, the version, and the date (above). 
  12.             Send bug reports to danwr@kagi.com. 
  13.     
  14.     Updates:     http://www.halcyon.com/danwr/smoothie.html
  15. */
  16.  
  17. #ifndef __FRAZAPI__
  18. #define __FRAZAPI__
  19.  
  20.  
  21. #if PRAGMA_ONCE
  22. #pragma once
  23. #endif
  24.  
  25. #ifdef __cplusplus
  26. extern "C"    {
  27. #endif
  28.  
  29. #if PRAGMA_IMPORT
  30. #pragma import on
  31. #endif
  32.  
  33. #if PRAGMA_STRUCT_ALIGN
  34.     #pragma options align=mac68k
  35. #elif PRAGMA_STRUCT_PACKPUSH
  36.     #pragma pack(push, 2)
  37. #elif PRAGMA_STRUCT_PACK
  38.     #pragma pack(2)
  39. #endif
  40.  
  41.  
  42. #ifndef FRAZ_OLDAPI
  43.     #define FRAZ_OLDAPI    0
  44. #endif
  45.  
  46. enum    {
  47. #if TARGET_API_MAC_CARBON
  48.     kFzecCurrentVersion = 2,
  49.     kFzabCurrentVersion = 2,
  50. #else
  51.     kFzecCurrentVersion = 0,
  52.     kFzabCurrentVersion = 0,
  53. #endif
  54.  
  55.     kFragmalyzerSignature    = FOUR_CHAR_CODE('FraZ'),
  56.     
  57.     kFrazCommandResourceType = FOUR_CHAR_CODE('Fzec'),
  58.     
  59.     kFrazCommandFileType    = FOUR_CHAR_CODE('Fzec'),
  60.     
  61.     kFrazBFXResourceType    = FOUR_CHAR_CODE('Fzab'),
  62.     
  63.     kFrazBFXFileType        = FOUR_CHAR_CODE('Fzab'),
  64.         
  65.     kSigPluginActive = 0,
  66.     
  67.     kSigPluginNone = 0
  68.     };
  69.  
  70. #if FRAZ_OLDAPI
  71.     enum {
  72.         kFrazPluginFileType         = kFrazCommandFileType,
  73.         kFrazPluginResourceType    = kFrazCommandResourceType,
  74.         };
  75. #endif // FRAZ_OLDAPI
  76.  
  77. /*
  78.      Menu IDs 
  79. */
  80. enum {
  81.     kFrazMenuFile        = 1001,
  82.     kFrazMenuEdit,
  83.     kFrazMenuFragmalyze,
  84.     kFrazMenuSymbol,
  85.     
  86.     kFrazMenuUserMin    = 2000,
  87.     kFrazMenuUserMax    = 2009,
  88.     
  89.     
  90.     kFrazMenuBar        = 0,        /* menu id for adding menus to the menubar */
  91.     
  92.     kFrazCmdInsertAtDefaultLocation = 0 /* use with FrazInsertCommand for default behavior */    
  93.     };
  94.  
  95.     
  96. /*
  97.     Command IDs
  98. */
  99. enum {
  100.     kFrazCmdUndo        = 11,
  101.     kFrazCmdCut         = 12,
  102.     kFrazCmdCopy        = 13,
  103.     kFrazCmdPaste        = 14,
  104.     kFrazCmdClear        = 15
  105.     };
  106.     
  107. /*
  108.     ctEnableFlags
  109.     - indicate conditions under which commands are enabled/disabled
  110. */
  111. enum {
  112.     kctAlways    =    0,        /* always enabled */
  113.     kctBrowser,                /* requires active browser window */
  114.     kctFragment,                /* requires selected fragment */
  115.     kctImportLibrary,            /* requires selected import library */
  116.     kctApplication,                /* requires selected application fragment */
  117.     kctReserved5,                /* reserved for future use */
  118.     kctReserved6,                /* reserved for future use */
  119.     kctPluginWindow,            /* requires active plug-in window */
  120.  
  121.     kctImportSymbol =    8,        /* requires that 1+ import symbols be selected */
  122.     kctExportSymbol =    16,        /* requires that 1+ export symbols be selected */
  123.     kctSymbol =    (kctImportSymbol | kctExportSymbol),  /* any kind of symbol will do */
  124.     kctExactlyOneSymbol = 32,    /* requires that ONLY 1 symbol be selected */
  125.     
  126.     kctReservedx40    = 64,
  127.     
  128.     kctDoubleClickAction = 0x0080, /* can handle double-click */
  129.     
  130.     kctReservedx100 =    0x0100,
  131.     kctReservedx200    = 0x200,
  132.     
  133.     kctWriteAccess =    0x0400,    /* browser/fragment must be modifiable */
  134.     kctProcess =        0x0800,    /* context browsers only */
  135.     kctNeedsCall =        0x1000,    /* always call FindCommandStatus */
  136.     kctCallEnabled =     0x2000,    /* call FindCommandStatus only if command appears to be enabled (according to other conditions) */
  137.  
  138.     kctReservedx4000    = 0x4000,
  139.     kctReservedx8000    = 0x8000,
  140.     
  141.     kctMaskGeneral =    0x1F
  142.     };
  143.  
  144.  
  145. #ifdef __cplusplus
  146.     inline Boolean IsStandardCommand(UInt32 cmd)
  147.     {
  148.         return (cmd & 0xFFFF0000) == 0;
  149.     }
  150.     
  151.     inline UInt16 GetPluginCommandID(UInt32 cmd)
  152.     {
  153.         return IsStandardCommand(cmd) ? 0 : (cmd & 0x0000FFFF);
  154.     }
  155.     
  156.     #define OPTIONAL_     =0
  157. #else
  158.     #define GetPluginCommandID(cmd) ((cmd) & 0xFFFF)
  159.     #define IsStandardCommand(cmd)    (((cmd) & 0xFFFF0000) == 0)
  160.     
  161.     #define OPTIONAL_        
  162. #endif
  163.     
  164.     
  165. /*——————————————————————————————————————————————————————————————
  166.     O P A Q U E   R E F E R E N C E S
  167.   ——————————————————————————————————————————————————————————————*/
  168. typedef struct OpaqueBrowser        *BrowserRef;
  169. typedef struct OpaqueFragment        *FragmentRef;
  170. typedef struct OpaqueLibrary        *LibraryRef;
  171.  
  172. typedef struct OpaqueProgress         *ProgressRef;
  173.  
  174. typedef struct OpaquePlugin        *PluginRef;
  175.  
  176.  
  177. /*——————————————————————————————————————————————————————————————
  178.     F R A Z  P A R A M
  179.   ——————————————————————————————————————————————————————————————*/
  180. typedef struct FrazParam
  181.     {
  182.     WindowRef    window;        /* the active window */
  183.     BrowserRef     browser;        /* the active browser (or browser being acted upon) */
  184.     FragmentRef     fragment;        /* the selected fragment (or fragment " ") */
  185.     LibraryRef    library;        /* the selected import library (or library " ") */
  186.     DescType        dtAE;        /* for HandleAppleEvent, this is the eventID;
  187.                                 FrazResolveDesc places the class of the object here. */
  188.     UInt16        isymbol;        /* used only by FrazResolveDesc (because selection can 
  189.                                 include more than one symbol). It is an export symbol
  190.                                 iff libSelected == nil. */
  191.     UInt16        _reserved;    /* reserved for future use */
  192.     } FrazParam;
  193.     
  194.  
  195.  
  196. #if FRAZ_OLDAPI
  197. /*——————————————————————————————————————————————————————————————
  198.     F R A Z  F R A G M E N T  I N F O
  199.   ——————————————————————————————————————————————————————————————*/
  200. typedef struct FrazFragmentInfo
  201.     {
  202.     StringPtr            pstName;             /* [RO] name of fragment */
  203.     CFragContextID     context;             /* [RO] 0/nil if on disk */
  204.     CFragConnectionID    conn;                 /* [RO] 0/nil if on disk */
  205.     
  206.     SInt32             dirAppLibraries;     /* aliased directory in 'cfrg' (or 0) */
  207.     SInt32             cbAppStack;        /* application stack (or 0) */
  208.     SInt32             updateLevel;        /* base fragment (0) or update */
  209.     CFragUsage         usage;            /* fragment usage (app, shared lib, plugin,...) */
  210.     UInt8            padding;
  211.     
  212.     /* from PEF file header */
  213.     UInt32            architectureID;        /* PowerPC or 68k */
  214.     UInt32            version;
  215.     UInt32            timestamp;
  216.     UInt32            oldDefVersion;
  217.     UInt32            oldImpVersion;
  218.     UInt32            currentVersion;
  219.     } FrazFragmentInfo;
  220. #endif // FRAZ_OLDAPI    
  221.  
  222. /*——————————————————————————————————————————————————————————————
  223.     F R A Z  W I N D O W  B O U N D S
  224.   ——————————————————————————————————————————————————————————————*/
  225. typedef struct FrazWindowBounds
  226.     {
  227.     UInt16    widthMin;
  228.     UInt16    heightMin;
  229.     UInt16    widthMax;
  230.     UInt16    heightMax;
  231.     UInt16    widthIdeal;
  232.     UInt16    heightIdeal;
  233.     UInt32    reserved;
  234.     } FrazWindowBounds;
  235.     
  236.  
  237.     // kGeneralImportSymbols is not a real library, it is used for import symbols that are not
  238.     // associated with any library.
  239. const LibraryRef kGeneralImportSymbols = (LibraryRef)'hack';
  240.     
  241. enum    {
  242.     idxNil = 0,
  243.     isymNil = -1
  244.     };
  245.  
  246.  
  247. /*
  248.     Application-level
  249.     - informational, event-handling, command status, and browser-independent app features
  250. */
  251.  
  252.  
  253.  
  254.  
  255. pascal SInt32     FrazVersion(NumVersion *);
  256.  
  257. pascal void     FrazHandleEvent(EventRecord *);
  258.  
  259. pascal void     FrazDirtyCommandStatus(void);
  260.  
  261. pascal OSErr     FrazOpenContext(CFragContextID context);
  262.  
  263. pascal OSErr     FrazOpenProcess(ProcessSerialNumber *psn);
  264.  
  265. pascal void     FrazOpenFile(FSSpec *, Boolean fNewBrowser);
  266.  
  267. pascal void     FrazInsertCommand(UInt16 ctEnableFlags, UInt16 command, UInt16 mid, StringPtr stCommand, UInt32 insertBeforeCmd);
  268.  
  269. pascal void     FrazRemoveCommand(UInt32 command);
  270.  
  271. pascal int         FrazSetCommandKey(UInt16 command, UInt8 chKey, UInt8 modifiers);
  272.  
  273.  
  274.  
  275. /* 
  276.     Browsers
  277. */
  278. pascal void     FrazRefreshBrowser(BrowserRef);
  279.  
  280. pascal FragmentRef FrazGetIndFragment(BrowserRef, UInt16 index);
  281.  
  282. pascal void     FrazFindLibrarySet(BrowserRef, Boolean fMinimal);
  283.  
  284. pascal UInt16     FrazGetNextSelectedSymbol(BrowserRef, UInt16 indexLast);
  285.  
  286. pascal UInt16     FrazGetNextSelectedFragment(BrowserRef, UInt16 indexLast);
  287.  
  288.  
  289. /*
  290.     Fragments
  291. */
  292.  
  293. pascal LibraryRef FrazGetIndLibrary(FragmentRef, UInt16 index);
  294.  
  295.     /* Introduced in version 1.5 */
  296.  
  297. pascal OSErr FrazGetFragmentProperty(FragmentRef, DescType propertyTag, Size inBufferSize, void *pbuffer, 
  298.                             DescType *outType OPTIONAL_, Size *outActualSize OPTIONAL_);
  299.  
  300. pascal OSErr FrazGetSectionProperty(FragmentRef fragment, UInt16 index, DescType propertyTag, Size inBufferSize, 
  301.                             void *pbuffer, DescType *outType OPTIONAL_, Size *outActualSize OPTIONAL_);
  302.  
  303. #if FRAZ_OLDAPI
  304.         /* Deprecated; use FrazGetFragmentProperty instead */
  305.     pascal void FrazGetFragmentInfo(FragmentRef, FrazFragmentInfo *pinfo);
  306.  
  307.     pascal void FrazSetFragmentInfo(FragmentRef, FrazFragmentInfo *pinfo);
  308. #endif // FRAZ_OLDAPI
  309.  
  310. /*
  311.     Libraries
  312. */
  313.  
  314. pascal int         FrazFindLibraryFragments(LibraryRef, FragmentRef *rgfrag, int cfragMax);
  315.  
  316. #if FRAZ_OLDAPI
  317.     pascal void FrazGetLibraryInfo(LibraryRef, UInt32 *poldImpVersion, UInt32 *pCurrentVersion, UInt8 *pOptions, StringPtr pstName);
  318. #endif // FRAZ_OLDAPI
  319.  
  320.     /* Introduced in version 1.5 */
  321.     
  322. pascal OSErr     FrazGetLibraryProperty(LibraryRef, DescType propertyTag, void *, Size, DescType * OPTIONAL_, Size * OPTIONAL_);
  323.  
  324.  
  325. /*
  326.     Symbols
  327. */
  328. pascal OSErr     FrazGetSymbolInfo(FragmentRef, LibraryRef, UInt16 index, StringPtr st255, Boolean *pfWeak);
  329.  
  330. pascal void     FrazUnmangleSymbol(StringPtr inStMangled, StringPtr outStUnmangled);
  331.  
  332.     /* Introduced in version 1.5 */
  333.     
  334. pascal OSErr     FrazGetSymbolProperty(FragmentRef, LibraryRef, UInt32 isym, OSType property, void *, Size, DescType * OPTIONAL_, Size * OPTIONAL_);
  335.  
  336.  
  337. /*
  338.     Plug-in Windows
  339.         Claim ownership of a modeless window/dialog. Events will be sent to the plug-in's FilterEvent
  340.         and HandleCloseWindow entrypoints.
  341. */
  342.  
  343. #if TARGET_API_MAC_CARBON
  344.     /* Modified for version 2.0 */
  345.  
  346. pascal void    FrazMarkPluginWindow(PluginRef, WindowPtr);
  347.  
  348. #else
  349.  
  350. pascal void     FrazMarkPluginWindow(WindowPtr);
  351.  
  352. #endif
  353.  
  354. /*
  355.     AppleEvents
  356.     
  357.         Routines for creating/resolved AppleEvent objects, and for manipulating properties.
  358. */
  359.  
  360. /* The object class is returned in param->dtAE. Be aware that FrazResolveDesc
  361.     may not return the same class every time -- so be sure to check param->dtAE.
  362.     The superobjects are also filled in. This is the only case where isymbol may
  363.     be filled in. */
  364. pascal OSErr     FrazResolveDesc(AEDesc *inObject, FrazParam *param);
  365.  
  366. pascal OSErr     FrazMakeObject(FrazParam *param, DescType inClass, AEDesc *outObject);
  367.  
  368. /* FrazAESetProperty buillds a "set data" AppleEvent and sends it to the Fragmalyzer (send to self).
  369.     This will record the action (if recording is on), and will cause the action to be executed. */
  370. #define FrazAESetProperty            FrazSetProperty
  371. pascal OSErr     FrazAESetProperty(FrazParam *param, DescType inClass, DescType inProperty, AEDesc *inValue);
  372.  
  373.  
  374.  
  375. /*
  376.     Status/Progress reports 
  377. */
  378.  
  379. pascal ProgressRef FrazShowProgress(StringPtr stTitle, StringPtr stLine1, Boolean fIndeterminate);
  380.  
  381. pascal void     FrazSetProgressText(ProgressRef, StringPtr stLine1, StringPtr stLine2);  /* use nil if no change */
  382.  
  383. pascal Boolean     FrazUpdateProgress(ProgressRef, SInt32 percentDone /* ignored if fIndeterminate */); 
  384.  
  385. pascal void     FrazCloseProgress(ProgressRef, Boolean fDone);
  386.  
  387.  
  388.  
  389. /*
  390.     Alerts/messages
  391.     - use instead of StopAlert, NoteAlert, and CautionAlert
  392. */
  393.  
  394. pascal void     FrazStopAlert(StringPtr stMain, StringPtr stAlt);
  395.  
  396. pascal void     FrazNoteAlert(StringPtr stMain, StringPtr stAlt);
  397.  
  398. pascal SInt32     FrazCautionAlert(StringPtr stMain, StringPtr stAlt);
  399.  
  400.  
  401.  
  402. /*
  403.     Plug-ins
  404. */
  405.  
  406. pascal Boolean     FrazGetPluginInfo(OSType sigPlugin, FSSpec *, UInt16 *pVers);
  407.  
  408. pascal Boolean     FrazPluginObeyCommand(OSType sigPlugin, UInt16 cmd, FrazParam *);
  409.  
  410.     /* Introduced in version 1.5 */
  411.     
  412. /*    
  413.     FrazEnterPlugin/FrazLeavePlugin
  414.     - wrap custom entrypoints with these calls to ensure that the plugin is not
  415.     unloaded while its code is on the stack (this could happen if memory is sufficently
  416.     low, triggering the growZone proc).
  417.     
  418.     These calls must be balanced.
  419. */
  420. #if TARGET_API_MAC_CARBON
  421. pascal void    FrazEnterPlugin(PluginRef);
  422. pascal void    FrazLeavePlugin(PluginRef);
  423. #else
  424. pascal void     FrazEnterPlugin(void);
  425. pascal void     FrazLeavePlugin(void);
  426. #endif
  427.  
  428. /*
  429.     The Entrypoints 
  430.  
  431.     Boolean     ObeyCommand(UInt32 inCommand, FrazParam *param);
  432.     void        FindCommandStatus(UInt32 inCmd, FrazParam *param, Boolean &outEnabled, Boolean &outUsesMark, UInt16 &outMark, Str255 &outName);
  433.     OSErr     HandleAppleEvent(const AppleEvent *, AppleEvent *, FrazParam *param);
  434.     Boolean     FilterEvent(EventRecord *);
  435.     Boolean     HandleCloseWindow(WindowRef, Boolean fCanInteract);
  436.     void      SetWindowSize(WindowRef, short width, short height);
  437.     void      GetWindowLimits(WindowRef, FrazWindowBounds *);
  438.  
  439.     OSStatus    InitPlugin(PluginRef, long reserved);
  440. */
  441.  
  442. extern PluginRef    gPluginSelf;
  443.  
  444. #if PRAGMA_STRUCT_ALIGN
  445.     #pragma options align=reset
  446. #elif PRAGMA_STRUCT_PACKPUSH
  447.     #pragma pack(pop)
  448. #elif PRAGMA_STRUCT_PACK
  449.     #pragma pack()
  450. #endif
  451.  
  452. #ifdef PRAGMA_IMPORT_OFF
  453. #pragma import off
  454. #elif PRAGMA_IMPORT
  455. #pragma import reset
  456. #endif
  457.  
  458. #ifdef __cplusplus
  459.         }
  460. #endif
  461.  
  462. #ifdef __cplusplus
  463.     class StCustomEntrypoint
  464.         {
  465.     public:
  466.     #if TARGET_API_MAC_CARBON
  467.             StCustomEntrypoint()    { FrazEnterPlugin(gPluginSelf); };
  468.         virtual ~StCustomEntrypoint()    { FrazLeavePlugin(gPluginSelf); };
  469.     #else
  470.             StCustomEntrypoint()    { FrazEnterPlugin(); }
  471.         virtual ~StCustomEntrypoint()    { FrazLeavePlugin(); }
  472.     #endif
  473.         };
  474. #endif // __cplusplus
  475.  
  476. #endif /* __FRAZAPI__ */